<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <title>Overview | Fans</title>
    <meta name="description" content="The Fans app REST API docs.">
    <link rel="shortcut icon" href="/docs/favicon.ico">
  <link rel="icon" href="/docs/fans.svg">
  <link rel="mask-icon" href="/docs/fans.svg">
    
    <link rel="preload" href="/docs/assets/css/0.styles.96586f63.css" as="style"><link rel="preload" href="/docs/assets/js/app.adb254f4.js" as="script"><link rel="preload" href="/docs/assets/js/2.0613674a.js" as="script"><link rel="preload" href="/docs/assets/js/6.28cd1744.js" as="script"><link rel="prefetch" href="/docs/assets/js/10.443b0da9.js"><link rel="prefetch" href="/docs/assets/js/11.5914f244.js"><link rel="prefetch" href="/docs/assets/js/12.7e19e4ef.js"><link rel="prefetch" href="/docs/assets/js/13.bf31197c.js"><link rel="prefetch" href="/docs/assets/js/14.325025c5.js"><link rel="prefetch" href="/docs/assets/js/15.fe04ddd5.js"><link rel="prefetch" href="/docs/assets/js/16.db0ffebf.js"><link rel="prefetch" href="/docs/assets/js/3.f7ca2ebe.js"><link rel="prefetch" href="/docs/assets/js/4.c9eaa668.js"><link rel="prefetch" href="/docs/assets/js/5.19f5b095.js"><link rel="prefetch" href="/docs/assets/js/7.407974dd.js"><link rel="prefetch" href="/docs/assets/js/8.5d06e407.js"><link rel="prefetch" href="/docs/assets/js/9.08fd7d8a.js">
    <link rel="stylesheet" href="/docs/assets/css/0.styles.96586f63.css">
  </head>
  <body>
    <div id="app" data-server-rendered="true"><div class="theme-container"><header class="navbar"><div class="sidebar-button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" role="img" viewBox="0 0 448 512" class="icon"><path fill="currentColor" d="M436 124H12c-6.627 0-12-5.373-12-12V80c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12z"></path></svg></div> <a href="/docs/" class="home-link router-link-active"><!----> <span class="site-name">Fans</span></a> <div class="links"><div class="search-box"><input aria-label="Search" autocomplete="off" spellcheck="false" value=""> <!----></div> <nav class="nav-links can-hide"><div class="nav-item"><a href="/docs/" class="nav-link">Home</a></div><div class="nav-item"><a href="/docs/api/" class="nav-link router-link-exact-active router-link-active">Docs</a></div><div class="nav-item"><a href="https://github.com/medz/fans" target="_blank" rel="noopener noreferrer" class="nav-link external">
  GitHub
  <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></div> <!----></nav></div></header> <div class="sidebar-mask"></div> <aside class="sidebar"><nav class="nav-links"><div class="nav-item"><a href="/docs/" class="nav-link">Home</a></div><div class="nav-item"><a href="/docs/api/" class="nav-link router-link-exact-active router-link-active">Docs</a></div><div class="nav-item"><a href="https://github.com/medz/fans" target="_blank" rel="noopener noreferrer" class="nav-link external">
  GitHub
  <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></div> <!----></nav>  <ul class="sidebar-links"><li><section class="sidebar-group depth-0"><p class="sidebar-heading open"><span>Kernel</span> <!----></p> <ul class="sidebar-links sidebar-group-items"><li><a href="/docs/api/" class="active sidebar-link">Overview</a><ul class="sidebar-sub-headers"><li class="sidebar-sub-header"><a href="/docs/api/#root-endpoint" class="sidebar-link">Root endpoint</a></li><li class="sidebar-sub-header"><a href="/docs/api/#schema" class="sidebar-link">Schema</a></li><li class="sidebar-sub-header"><a href="/docs/api/#authentication" class="sidebar-link">Authentication</a></li><li class="sidebar-sub-header"><a href="/docs/api/#http-verbs" class="sidebar-link">HTTP verbs</a></li><li class="sidebar-sub-header"><a href="/docs/api/#rate-limiting" class="sidebar-link">Rate limiting</a></li></ul></li><li><a href="/docs/api/authorizations.html" class="sidebar-link">Authorizations</a></li><li><a href="/docs/api/comments.html" class="sidebar-link">Comments</a></li><li><a href="/docs/api/itc.html" class="sidebar-link">International Telephone Codes</a></li><li><a href="/docs/api/jurisdictions.html" class="sidebar-link">Jurisdictions</a></li><li><a href="/docs/api/talks.html" class="sidebar-link">Talks</a></li><li><a href="/docs/api/upload.html" class="sidebar-link">Upload File</a></li><li><a href="/docs/api/users.html" class="sidebar-link">Users</a></li></ul></section></li><li><section class="sidebar-group depth-0"><p class="sidebar-heading"><span>Forum</span> <!----></p> <ul class="sidebar-links sidebar-group-items"><li><a href="/docs/api/forum/nodes.html" class="sidebar-link">Nodes</a></li><li><a href="/docs/api/forum/threads.html" class="sidebar-link">Threads</a></li></ul></section></li></ul> </aside> <main class="page"> <div class="content default"><p>This describes the resources that make up the official REST API. If you have any problems or requests, please contact <a href="https://github.com/medz/fans/issues">Fans Support</a>.</p> <p></p><div class="table-of-contents"><ul><li><a href="#root-endpoint">Root endpoint</a></li><li><a href="#schema">Schema</a></li><li><a href="#authentication">Authentication</a><ul><li><a href="#failed-login-limit">Failed login limit</a></li><li><a href="#parameters">Parameters</a></li></ul></li><li><a href="#http-verbs">HTTP verbs</a><ul><li><a href="#simulation">Simulation</a></li></ul></li><li><a href="#rate-limiting">Rate limiting</a></li></ul></div><p></p> <h2 id="root-endpoint"><a href="#root-endpoint" aria-hidden="true" class="header-anchor">#</a> Root endpoint</h2> <p>In the next document, <code>http://fans.local.medz.cn</code> will be replaced with <code>{uri}</code>.</p> <h2 id="schema"><a href="#schema" aria-hidden="true" class="header-anchor">#</a> Schema</h2> <p>All API access is over HTTP(S), and accessed from <code>http://fans.local.medz.cn</code>. All data is sent and received as <strong>JSON</strong>.</p> <div class="language-yaml extra-class"><pre class="language-yaml"><code>curl <span class="token punctuation">-</span>i <span class="token punctuation">{</span>uri<span class="token punctuation">}</span>/auth/me
<span class="token key atrule">Transfer-Encoding</span><span class="token punctuation">:</span> chunked
<span class="token key atrule">Cache-Control</span><span class="token punctuation">:</span> no<span class="token punctuation">-</span>cache<span class="token punctuation">,</span> private
<span class="token key atrule">Content-Type</span><span class="token punctuation">:</span> application/json
<span class="token key atrule">Date</span><span class="token punctuation">:</span> Thu<span class="token punctuation">,</span> 14 Feb 2019 14<span class="token punctuation">:</span>11<span class="token punctuation">:</span>32 GMT
<span class="token key atrule">Keep-Alive</span><span class="token punctuation">:</span> timeout=38
<span class="token key atrule">Server</span><span class="token punctuation">:</span> nginx/1.15.8
<span class="token key atrule">X-Powered-By</span><span class="token punctuation">:</span> PHP/7.1.25
<span class="token key atrule">X-Ratelimit-Limit</span><span class="token punctuation">:</span> <span class="token number">60</span>
<span class="token key atrule">X-Ratelimit-Remaining</span><span class="token punctuation">:</span> <span class="token number">58</span>
</code></pre></div><p>Blank fields are included as null instead of being omitted.</p> <p>All timestamps return in ISO 8601 format:</p> <div class="language- extra-class"><pre class="language-text"><code>YYYY-MM-DDTHH:MM:SSZ
</code></pre></div><h2 id="authentication"><a href="#authentication" aria-hidden="true" class="header-anchor">#</a> Authentication</h2> <p>Sent in a header ways to authenticate through API. Requests that require authentication will return 404 Not Found, instead of 403 Forbidden, in some places. This is to prevent the accidental leakage of private data to unauthorized users.</p> <div class="language- extra-class"><pre class="language-text"><code>curl -H &quot;Authorization: Bearer ACCESS-TOKEN&quot; {uri}
</code></pre></div><h3 id="failed-login-limit"><a href="#failed-login-limit" aria-hidden="true" class="header-anchor">#</a> Failed login limit</h3> <p>Authenticating with invalid credentials will return 401 Unauthorized:</p> <div class="language-json extra-class"><pre class="language-json"><code>curl -H <span class="token string">&quot;Authorization: Bearer ACCESS-TOKEN&quot;</span> <span class="token punctuation">{</span>uri<span class="token punctuation">}</span>/auth/me
HTTP/<span class="token number">1.1</span> <span class="token number">401</span> Unauthorized
<span class="token punctuation">{</span>
    <span class="token property">&quot;message&quot;</span><span class="token operator">:</span> <span class="token string">&quot;Unauthenticated.&quot;</span>
<span class="token punctuation">}</span>
</code></pre></div><h3 id="parameters"><a href="#parameters" aria-hidden="true" class="header-anchor">#</a> Parameters</h3> <p>Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:</p> <div class="language- extra-class"><pre class="language-text"><code>curl -i &quot;{uri}/forum/threads?node=1&quot;
</code></pre></div><p>For POST, PATCH, PUT, and DELETE requests, <strong>parameters not included in the URL should be encoded as JSON</strong> with a Content-Type of <code>application/json</code>:</p> <div class="language-sh extra-class"><pre class="language-sh"><code><span class="token function">curl</span> -i -d <span class="token string">'{&quot;phone&quot;:&quot;1878*****73&quot;, &quot;international_telephone_code&quot;: &quot;+86&quot;}'</span> <span class="token punctuation">{</span>uri<span class="token punctuation">}</span>/auth/verify-code
</code></pre></div><h2 id="http-verbs"><a href="#http-verbs" aria-hidden="true" class="header-anchor">#</a> HTTP verbs</h2> <p>Where possible, API strives to use appropriate HTTP verbs for each action.</p> <table><thead><tr><th>Verb</th> <th>Description</th></tr></thead> <tbody><tr><td><code>HEAD</code></td> <td>Can be issued against any resource to get just the HTTP header info.</td></tr> <tr><td><code>GET</code></td> <td>Used for retrieving resources.</td></tr> <tr><td><code>POST</code></td> <td>Used for creating resources.</td></tr> <tr><td><code>PATCH</code></td> <td>Used for updating resources with partial JSON data. For instance, an Thread resource has <code>title</code> and <code>body</code> attributes. A PATCH request may accept one or more of the attributes to update the resource. PATCH is a relatively new and uncommon HTTP verb, so resource endpoints also accept <code>POST</code> requests.</td></tr> <tr><td><code>PUT</code></td> <td>Used for replacing resources or collections. For <code>PUT</code> requests with no <code>body</code> attribute, be sure to set the <code>Content-Length</code> header to zero.</td></tr> <tr><td><code>DELETE</code></td> <td>Used for deleting resources.</td></tr></tbody></table> <h3 id="simulation"><a href="#simulation" aria-hidden="true" class="header-anchor">#</a> Simulation</h3> <p>Sometimes the client environment supports the use of HTTP verbs, so all APIs support emulation using <code>POST</code> verb passing. Use the <code>_method</code> parameter to simulate the HTTP verb that needs to be simulated. E.g:</p> <div class="language- extra-class"><pre class="language-text"><code>curl -i -d '{&quot;_method&quot;: &quot;DELETE&quot;}' {uri}/comments/1
</code></pre></div><h2 id="rate-limiting"><a href="#rate-limiting" aria-hidden="true" class="header-anchor">#</a> Rate limiting</h2> <p>The returned HTTP headers of any API request show your current rate limit status:</p> <div class="language-yaml extra-class"><pre class="language-yaml"><code>curl <span class="token punctuation">-</span>i <span class="token punctuation">{</span>uri<span class="token punctuation">}</span>/users
HTTP/1.1 200 OK
<span class="token key atrule">Date</span><span class="token punctuation">:</span> Thu<span class="token punctuation">,</span> 14 Feb 2019 14<span class="token punctuation">:</span>11<span class="token punctuation">:</span>32 GMT
<span class="token key atrule">Status</span><span class="token punctuation">:</span> 200 OK
<span class="token key atrule">X-RateLimit-Limit</span><span class="token punctuation">:</span> <span class="token number">60</span>
<span class="token key atrule">X-RateLimit-Remaining</span><span class="token punctuation">:</span> <span class="token number">56</span>
</code></pre></div></div> <footer class="page-edit"><!----> <!----></footer> <div class="page-nav"><p class="inner"><!----> <span class="next"><a href="/docs/api/authorizations.html">
          Authorizations
        </a>
        →
      </span></p></div> </main></div><div class="global-ui"></div></div>
    <script src="/docs/assets/js/app.adb254f4.js" defer></script><script src="/docs/assets/js/2.0613674a.js" defer></script><script src="/docs/assets/js/6.28cd1744.js" defer></script>
  </body>
</html>
